home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Checkbox.java < prev    next >
Text File  |  1998-09-22  |  14KB  |  430 lines
  1. /*
  2.  * @(#)Checkbox.java    1.42 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.peer.CheckboxPeer;
  17. import java.awt.event.*;
  18. import java.io.ObjectOutputStream;
  19. import java.io.ObjectInputStream;
  20. import java.io.IOException;
  21.  
  22.  
  23. /**
  24.  * A check box is a graphical component that can be in either an 
  25.  * "on" (<code>true</code>) or "off" (<code>false</code>) state.
  26.  * Clicking on a check box changes its state from 
  27.  * "on" to "off," or from "off" to "on." 
  28.  * <p>
  29.  * The following code example creates a set of check boxes in
  30.  * a grid layout: 
  31.  * <p>
  32.  * <hr><blockquote><pre>
  33.  * setLayout(new GridLayout(3, 1));
  34.  * add(new Checkbox("one", null, true));
  35.  * add(new Checkbox("two"));
  36.  * add(new Checkbox("three"));
  37.  * </pre></blockquote><hr>
  38.  * <p>
  39.  * This image depicts the check boxes and grid layout
  40.  * created by this code example:
  41.  * <p>
  42.  * <img src="images-awt/Checkbox-1.gif"
  43.  * ALIGN=center HSPACE=10 VSPACE=7>
  44.  * <p>
  45.  * The button labeled <code>one</code> is in the "on" state, and the 
  46.  * other two are in the "off" state. In this example, which uses the
  47.  * <code>GridLayout</code> class, the states of the three check 
  48.  * boxes are set independently.
  49.  * <p>
  50.  * Alternatively, several check boxes can be grouped together under 
  51.  * the control of a single object, using the 
  52.  * <code>CheckboxGroup</code> class. 
  53.  * In a check box group, at most one button can be in the "on" 
  54.  * state at any given time. Clicking on a check box to turn it on
  55.  * forces any other check box in the same group that is on 
  56.  * into the "off" state.
  57.  *
  58.  * @version    1.42 07/01/98
  59.  * @author     Sami Shaio
  60.  * @see         java.awt.GridLayout
  61.  * @see         java.awt.CheckboxGroup
  62.  * @since       JDK1.0
  63.  */
  64. public class Checkbox extends Component implements ItemSelectable {
  65.     /**
  66.      * The label of the Checkbox.
  67.      */
  68.     String label;
  69.  
  70.     /**
  71.      * The state of the Checkbox.
  72.      */
  73.     boolean state;
  74.  
  75.     /**
  76.      * The check box group.
  77.      */
  78.     CheckboxGroup group;
  79.  
  80.     transient ItemListener itemListener;
  81.  
  82.     private static final String base = "checkbox";
  83.     private static int nameCounter = 0;
  84.  
  85.     /*
  86.      * JDK 1.1 serialVersionUID 
  87.      */
  88.     private static final long serialVersionUID = 7270714317450821763L;
  89.  
  90.     /**
  91.      * Helper function for setState and CheckboxGroup.setSelectedCheckbox
  92.      * Should remain package-private.
  93.      */
  94.     void setStateInternal(boolean state) {
  95.     this.state = state;
  96.     CheckboxPeer peer = (CheckboxPeer)this.peer;
  97.     if (peer != null) {
  98.         peer.setState(state);
  99.     }
  100.     }
  101.  
  102.     /**
  103.      * Creates a check box with no label. The state of this 
  104.      * check box is set to "off," and it is not part of any 
  105.      * check box group. 
  106.      * @since     JDK1.0
  107.      */
  108.     public Checkbox() {
  109.         this("", false, null);
  110.     }
  111.  
  112.     /**
  113.      * Creates a check box with the specified label.  The state 
  114.      * of this check box is set to "off," and it is not part of  
  115.      * any check box group. 
  116.      * @param     label   a string label for this check box, 
  117.      *                        or <code>null</code> for no label.
  118.      * @since     JDK1.0
  119.      */
  120.     public Checkbox(String label) {
  121.     this(label, false, null);
  122.     }
  123.  
  124.     /**
  125.      * Creates a check box with the specified label.  The state 
  126.      * of this check box is as specified by the <code>state</code> 
  127.      * argument, and it is not part of any check box group. 
  128.      * @param     label   a string label for this check box, 
  129.      *                        or <code>null</code> for no label.
  130.      * @param     state    the initial state of this check box.
  131.      * @since     JDK1.0
  132.      */
  133.     public Checkbox(String label, boolean state) {
  134.         this(label, state, null);
  135.     }
  136.  
  137.     /**
  138.      * Creates a check box with the specified label, in the specified 
  139.      * check box group, and set to the specified state. 
  140.  
  141.      * @param     label   a string label for this check box, 
  142.      *                        or <code>null</code> for no label.
  143.      * @param     state   the initial state of this check box.
  144.      * @param     group   a check box group for this check box, 
  145.      *                           or <code>null</code> for no group.
  146.      * @since     JDK1.1
  147.      */
  148.     public Checkbox(String label, boolean state, CheckboxGroup group) {
  149.     this.label = label;
  150.     this.state = state;
  151.     this.group = group;
  152.     if (state && (group != null)) {
  153.         group.setSelectedCheckbox(this);
  154.     }
  155.     }
  156.  
  157.     /**
  158.      * Constructs a Checkbox with the specified label, set to the
  159.      * specified state, and in the specified check box group.
  160.      */
  161.     public Checkbox(String label, CheckboxGroup group, boolean state) {
  162.         this(label, state, group);
  163.     }
  164.  
  165.     /**
  166.      * Construct a name for this component.  Called by getName() when the
  167.      * name is null.
  168.      */
  169.     String constructComponentName() {
  170.         return base + nameCounter++;
  171.     }
  172.  
  173.     /**
  174.      * Creates the peer of the Checkbox. The peer allows you to change the
  175.      * look of the Checkbox without changing its functionality.
  176.      * @see     java.awt.Toolkit#createCheckbox(java.awt.Checkbox)
  177.      * @see     java.awt.Component#getToolkit()
  178.      * @since   JDK1.0
  179.      */
  180.     public void addNotify() {
  181.         synchronized (getTreeLock()) {
  182.         if (peer == null)
  183.             peer = getToolkit().createCheckbox(this);
  184.         super.addNotify();
  185.         }
  186.     }
  187.  
  188.     /**
  189.      * Gets the label of this check box.
  190.      * @return   the label of this check box, or <code>null</code> 
  191.      *                  if this check box has no label.
  192.      * @see      java.awt.Checkbox#setLabel
  193.      * @since    JDK1.0
  194.      */
  195.     public String getLabel() {
  196.     return label;
  197.     }
  198.  
  199.     /**
  200.      * Sets this check box's label to be the string argument. 
  201.      * @param    label   a string to set as the new label, or 
  202.      *                        <code>null</code> for no label.
  203.      * @see      java.awt.Checkbox#getLabel 
  204.      * @since    JDK1.0
  205.      */
  206.     public synchronized void setLabel(String label) {
  207.     this.label = label;
  208.     CheckboxPeer peer = (CheckboxPeer)this.peer;
  209.     if (peer != null) {
  210.         peer.setLabel(label);
  211.     }
  212.     }
  213.  
  214.     /** 
  215.      * Determines whether this check box is in the "on" or "off" state.
  216.      * The boolean value <code>true</code> indicates the "on" state,  
  217.      * and <code>false</code> indicates the "off" state.
  218.      * @return    the state of this check box, as a boolean value. 
  219.      * @see       java.awt.Checkbox#setState  
  220.      * @since     JDK1.0
  221.      */
  222.     public boolean getState() {
  223.     return state;
  224.     }
  225.     
  226.     /** 
  227.      * Sets the state of this check box to the specified state. 
  228.      * The boolean value <code>true</code> indicates the "on" state,  
  229.      * and <code>false</code> indicates the "off" state.
  230.      * @param     state   the boolean state of the check box.
  231.      * @see       java.awt.Checkbox#getState  
  232.      * @since     JDK1.0
  233.      */
  234.     public void setState(boolean state) {
  235.     /* Cannot hold check box lock when calling group.setSelectedCheckbox. */
  236.         CheckboxGroup group = this.group;
  237.     if (group != null) {
  238.         if (state) {
  239.         group.setSelectedCheckbox(this);
  240.         } else if (group.getSelectedCheckbox() == this) {
  241.         state = true;
  242.         }
  243.     }
  244.     setStateInternal(state);
  245.     }
  246.  
  247.     /**
  248.      * Returns the an array (length 1) containing the checkbox
  249.      * label or null if the checkbox is not selected.
  250.      * @see ItemSelectable
  251.      */
  252.     public Object[] getSelectedObjects() {
  253.         if (state) {
  254.             Object[] items = new Object[1];
  255.             items[0] = label;
  256.             return items;
  257.         }
  258.         return null;
  259.     }
  260.  
  261.     /**
  262.      * Determines this check box's group. 
  263.      * @return     this check box's group, or <code>null</code> 
  264.      *               if the check box is not part of a check box group.
  265.      * @see        java.awt.Checkbox#setCheckboxGroup 
  266.      * @since      JDK1.0
  267.      */
  268.     public CheckboxGroup getCheckboxGroup() {
  269.     return group;
  270.     }
  271.  
  272.     /**
  273.      * Sets this check box's group to be the specified check box group. 
  274.      * If this check box is already in a different check box group, 
  275.      * it is first taken out of that group. 
  276.      * @param     g   the new check box group, or <code>null</code> 
  277.      *                to remove this check box from any check box group.
  278.      * @see       java.awt.Checkbox#getCheckboxGroup  
  279.      * @since     JDK1.0
  280.      */
  281.     public void setCheckboxGroup(CheckboxGroup g) {
  282.         CheckboxGroup group = this.group;
  283.     if (group != null) {
  284.         group.setSelectedCheckbox(null);
  285.     }
  286.     /* Locking check box above could cause deadlock with
  287.      * CheckboxGroup's setSelectedCheckbox method.
  288.      */
  289.     synchronized (this) {
  290.         this.group = g;
  291.         CheckboxPeer peer = (CheckboxPeer)this.peer;
  292.         if (peer != null) {
  293.         peer.setCheckboxGroup(g);
  294.         }
  295.     }
  296.     }
  297.  
  298.     /**
  299.      * Adds the specified item listener to receive item events from
  300.      * this check box.
  301.      * @param         l    the item listener.
  302.      * @see           java.awt.event.ItemEvent
  303.      * @see           java.awt.event.ItemListener
  304.      * @see           java.awt.Checkbox#removeItemListener
  305.      * @since         JDK1.1
  306.      */ 
  307.     public synchronized void addItemListener(ItemListener l) {
  308.         itemListener = AWTEventMulticaster.add(itemListener, l);
  309.         newEventsOnly = true;
  310.     }
  311.  
  312.     /**
  313.      * Removes the specified item listener so that the item listener 
  314.      * no longer receives item events from this check box. 
  315.      * @param         l    the item listener.
  316.      * @see           java.awt.event.ItemEvent
  317.      * @see           java.awt.event.ItemListener
  318.      * @see           java.awt.Checkbox#addItemListener
  319.      * @since         JDK1.1
  320.      */ 
  321.     public synchronized void removeItemListener(ItemListener l) {
  322.         itemListener = AWTEventMulticaster.remove(itemListener, l);
  323.     }
  324.  
  325.     // REMIND: remove when filtering is done at lower level
  326.     boolean eventEnabled(AWTEvent e) {
  327.         if (e.id == ItemEvent.ITEM_STATE_CHANGED) {
  328.             if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||
  329.                 itemListener != null) {
  330.                 return true;
  331.             }             
  332.             return false;
  333.         }
  334.         return super.eventEnabled(e);
  335.     }          
  336.  
  337.     /**
  338.      * Processes events on this check box. 
  339.      * If the event is an instance of <code>ItemEvent</code>,
  340.      * this method invokes the <code>processItemEvent</code> method. 
  341.      * Otherwise, it calls its superclass's <code>processEvent</code> method.
  342.      * @param         e the event.
  343.      * @see           java.awt.event.ItemEvent
  344.      * @see           java.awt.Checkbox#processItemEvent
  345.      * @since         JDK1.1
  346.      */
  347.     protected void processEvent(AWTEvent e) {
  348.         if (e instanceof ItemEvent) {
  349.             processItemEvent((ItemEvent)e);
  350.             return;
  351.         }
  352.     super.processEvent(e);
  353.     }
  354.  
  355.     /** 
  356.      * Processes item events occurring on this check box by
  357.      * dispatching them to any registered 
  358.      * <code>ItemListener</code> objects. 
  359.      * <p>
  360.      * This method is not called unless item events are 
  361.      * enabled for this component. Item events are enabled 
  362.      * when one of the following occurs:
  363.      * <p><ul>
  364.      * <li>An <code>ItemListener</code> object is registered 
  365.      * via <code>addItemListener</code>.
  366.      * <li>Item events are enabled via <code>enableEvents</code>.
  367.      * </ul>
  368.      * @param       e the item event.
  369.      * @see         java.awt.event.ItemEvent
  370.      * @see         java.awt.event.ItemListener
  371.      * @see         java.awt.Checkbox#addItemListener
  372.      * @see         java.awt.Component#enableEvents
  373.      * @since       JDK1.1
  374.      */  
  375.     protected void processItemEvent(ItemEvent e) {
  376.         if (itemListener != null) {
  377.             itemListener.itemStateChanged(e);
  378.         }
  379.     }
  380.  
  381.     /**
  382.      * Returns the parameter string representing the state of 
  383.      * this check box. This string is useful for debugging. 
  384.      * @return    the parameter string of this check box.
  385.      * @since     JDK1.0
  386.      */
  387.     protected String paramString() {
  388.     String str = super.paramString();
  389.     String label = this.label;
  390.     if (label != null) {
  391.         str += ",label=" + label;
  392.     }
  393.     return str + ",state=" + state;
  394.     }
  395.  
  396.  
  397.     /* Serialization support. 
  398.      */
  399.  
  400.     private int checkboxSerializedDataVersion = 1;
  401.  
  402.  
  403.     private void writeObject(ObjectOutputStream s)
  404.       throws java.io.IOException 
  405.     {
  406.       s.defaultWriteObject();
  407.  
  408.       AWTEventMulticaster.save(s, itemListenerK, itemListener);
  409.       s.writeObject(null);
  410.     }
  411.  
  412.  
  413.     private void readObject(ObjectInputStream s)
  414.       throws ClassNotFoundException, IOException 
  415.     {
  416.       s.defaultReadObject();
  417.  
  418.       Object keyOrNull;
  419.       while(null != (keyOrNull = s.readObject())) {
  420.     String key = ((String)keyOrNull).intern();
  421.  
  422.     if (itemListenerK == key) 
  423.       addItemListener((ItemListener)(s.readObject()));
  424.  
  425.     else // skip value for unrecognized key
  426.       s.readObject();
  427.       }
  428.     }
  429. }
  430.